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1 apps 



DE.FRAUNHOFER.SIT.TC.ETHEMBA.APPS 

This package contains applications for TPM maintenance on the one hand and client- and 
server- applications that implement AIK- Certification and Remote-Attestation on the other 
hand. 



TakeOwnership and ClearOwnership permit TPM activation capabilities 



ManageKnownHashesList helps managing hash lists, that define trusted applications 



used in Remote-Attestation on the server-side 
PCAserver and PCAc/z'en1| implement AIK-Certification 



• RAserver and RAclient implement Remote-Attestation 
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1 apps 



1.1 ClearOwnership 
1.1.1 Description 

ClearOwnership clears the ownership of the TPM. The code is mainly based on the original 



jTpmtools (see Reference^ application. It can be used in the process of resetting the TPM to its 



initial state. A reboot might be required for changes to take effect. The current owner password 
is supplied as command-line parameter. 

For convenience and tests, the switch /f provides a fixed mode, reading the globally set 
owner password. 

Note: In our test scenario, routing the TPM-Emulator into a virtualized sub-system, we were 
able to clear the ownership without supplying the correct owner password. It is still to be 
clarified, if this is an issue with the emulated environment or the implementation in jTSS. 



1.1.2 PUBLIC main 
Description 

Called when used in command-line. 



Settings 

OwnerPwd 
Parameters 

String [] args [1] owner password or globally set owner password when 

used in fixed mode (7f). 

Output 

If no command line parameters are given, a usage information is displayed. 



1.2 TakeOwnership 
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1.2 TakeOwnership 
1.2.1 Description 

TakeOwnership allows taking ownership of the TPM. The owner password is set, a new SRK 
is generated inside the TPM and the SRK password is set. The code is mainly based on the 
original jTpmtools [see \Referencetf application. 

The owner and SRK passwords are supplied as command-line parameters. For convenience 
and tests, the switch 7f provides a fixed mode, reading the globally set owner and SRK pass- 
words. 



1.2.2 PUBLIC main 
Description 

Called when used in command-line. 



Settings 




OwnerPwd, SRKPwd 




Parameters 




String [] args 


[1] owner password or 7f for fixed mode 




[2] srk password 



Output 

If no command line parameters are given, a usage information is displayed. 
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1 apps 



1.3 ManageKnownHashesList 
1.3.1 Description 



ManageKnownHashesList takes an IMA-formatted file as input and converts it to a Known- 



HashesList This application can be used to create and maintain a database of known hashes. 
Used in append-mode (command line parameter /a), the contents of the input will be ap- 
pended to the database. Used in overwrite-mode (command line parameter /o), the contents 
of the input will overwrite an existing database. If no command line parameter is given, a man- 
agement console is presented to the user, allowing for view, search and remove entries of the 
database. 



1.3.2 PUBLIC main 
Description 

Called when used in command-line. 



Settings 




RAServer_KnownHashesList 




Parameters 




String[] args 


[1] /a or /o to enable append- or overwrite-mode (op- 




tional) 




[2] filename of IMA-Measurement-File to be used when 




[1] is set 



Output 

If no command line parameters are given, a management console providing view, search and 
remove functions is presented to the user. Otherwise the new or updated database of known 
hashes is stored in RAServer_KnownHashesList. 



1.3.3 PRIVATE append 
Description 

appends contents of given IMA-Measurement-File to existing database. 



Settings 

FAServer_KnownHashesList 
Parameters 

String file IMA-Measurement-File 



1.3.4 PRIVATE overwrite 
Description 

overwrites existing database with contents of given IMA-Measurement-File. 



1.3 ManageKnownHashesList 
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Settings 

RAServer_KnownHashesList 
Parameters 

String file IMA-Measurement-File 

1.3.5 PRIVATE view 
Description 

displays the entries contained in the KnownHashesList pagewise (blocks of 10 entries) 

Settings 

none 

Parameters 

none 

1.3.6 PRIVATE search 
Description 

displays the entries contained in the KnownHashesList matching the given search string 

Settings 
none 

Parameters 

String s search string to be used 

1.3.7 PRIVATE remove 
Description 

removes entries contained in the KnownHashesList matching the given search string 

Settings 
none 

Parameters 

String s search string to be used 



12 



1 apps 



1.4 PCAclient 



The PCAclient can be used to create and certify an AIK. The client creates a new AIK using 



the TPM_CollateIdentityRequest. The public part of it is sent to a PCAserver including the 



Endorsement Certificate. They are encrypted using the PCAservel\ s public key. Upon receipt, 
the PCAserver can decrypt the contents and verify the Endorsement Certificate. The PCAserver 
then creates a random nonce and wraps it for the client. The response contains two parts: 

1. a symmetric session key and the hash of the AIK public key, both encrypted with the EK 
public key 

2. the nonce, encrypted with the session key 



for details see PrivacyCa state3_sub. 



Using the TPM_ActivateIdentity command, the TPM can decrypt the answer and the nonce 
is revealed to the client. Only the client with the TPM used for creation of the AIK is able to 



decrypt the nonce. The client then sends the decrypted nonce back to the PCAserver 



Upon receipt and verification, the PCAserver\ will create a certificate for the AIK. It is then 



encrypted using an AES key. The AES key is wrapped for the client using the same scheme as 
for the nonce, thus the response consists of three parts: 

1. a symmetric session key and the hash of the AIK public key, both encrypted with the EK 
public key 



2. the AES key encrypted with the session key 



3. the AIK-Certificate, encrypted with the AES| key 



for details see PrivacyCa state5_sub. 



The AIK is activated by the client via a TPM_ActivateIdentity call. The AES key is decrypted 
and can be used to decrypt the AIK-Certificate. 

The client then assigns a UUID to the AIK and stores it in the System Persistent Storage of 



jTSS. For later access, the key is registered in the client.TpmKeyDB using the provided AIK 



label. As final step the AIK-Certificate is stored in the client.CertDB 



The client is separated into different methods representing each state of the protocol. The 
methods are called subsequently. 
Parameters 

needed to load the EK certificate / EK public key 
needed to store the new AIK 
will be needed when the AIK is accessed later on 
a label providing identification of the AIK. This label can 



owner password 
SRK password 
AIK password 
AIK label 




later be used to load the AIK from client.TpmKeyDB and 
will also be included in the certificate. 
IP address of the PCA server 



PCA server IP address 
PCA server port port of the PCA server, see Settings for default value 

All required parameters can be set from the command-line, a fixed mode is provided via the 
switch 'If. The required parameters will then be read from Settings. 



1.4 PCAclient 



13 




TPM 





Client 






TPM_Makeldentity 




retrieve EK certificate EKcert 



PCA Server 



■INIT- 
■ACK 



PCA_REQUEST- 
ACK 



TPM_I DE NTITY_CONTE NTS +sign. | EKcert 



Load AIK 



create random nonce 



enc{nonce, AIK p ^> EK[)ub 



encrypt nonce, AIK oub with EK| 



TPM_ActivateIdentity 
decrypt nonce 



nonce 

ACK 



enc{TPM_EK_BLOB> E|<pub | enc{cert} K 



check EKcert 



validate signature on 
TPM IDENTITY CONTENTS 



create cert(AIK,PCA ) 



encr. cert(AIK,PCA rr . rt ) with K 



encr. TPM EK BLOB with EK 



TPM_ActivateIdentity 
decrypt K, decrypt cert 



-CLOSE - 
— ACK— 



save cert(AIK,PCA ) 



Figure 1.1: protocol diagram for AIK-Certification 
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1 apps 



1.5 PCAserver 



The server is separated into different methods representing each state of the AIK-Certification 
protocol. The methods are called subsequently. 
-» see[ 



PCAclient for a detailed description of the AIK-Certification protocol 



1.6 RAclient 
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1.6 RAclient 



The RAclient can be used to perform a Remote-Attestation. Integrated Measurement Ar- 
chitecture (IMA) is used to provide runtime analysis of the client's system state. PCR-10 is 
constantly being extended with hashes of newly run programs. A client is being attested by 
a Remote-Attestation-Server by sending an AIK-signed quote of PCR-10 altogether with the 



corresponding AIK- Certificate and a \MeasurementLisi to the server. 

The quote is protected from replay- attacks by including a nonce, the Remote-Attestation- 
Server challenged the client with. By letting the TPM quote PCR- 10 internally integrity of PCR- 
10 is ensured. 

Upon receipt, the Remote-Attestation-Server performs several checks to attests the client's 
system state. First of all the AIK- Certificate is checked for validity (timestamp, signature and 



trusted issuer). Then the submitted MeasurementList is validated by checking each run appli- 
cation for known and trusted hashes. This results in a re-calculated PCR-10. At last the sub- 
mitted quote is being validated by checking its signature, the included nonce (for anti-replay!) 
and equality of the included PCR-10 and the re-calculated one. 

This equality check is highly required to ensure an attacker did not trick the Remote-Attestation- 



Server by submitting a fake MeasurementList 



After verification the client will receive a certificate from RAserver certifying platform in- 
tegrity. Note that this certificate has to be invalid after a short period of time, as the client's 
state might change very quickly. 



The RAclient stores the Attestation-Certificate in the client.CertDB using a new UUID. The 



UUID for the Attestation-Certificate is based on the UUID of the AIK used in the protocol. It 
can be accessed for later use via the UUID 00000009-0008-0007-060 5-aikUuid.getNode(). 

The client is separated into different methods representing each state of the protocol. The 
methods are called subsequently. 

Parameters 

SRK password needed to load the AIK 

AIK password needed to load the AIK 

AIK label the label the to be used AIK is stored under 

RA server IP address IP address of the RA server 

RA server port port of the RA server, see Settings for default value 

All required parameters can be set from the command-line, a fixed mode is provided via the 
switch 7f. The required parameters will then be read from Settings. 
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1 apps 



Client 
attesting system 



RA Server 
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-RA_REQUEST- 
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retrieve Measurement list ML 
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ACK 
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calculated Fi ll 



— ACK— 



Figure 1.2: protocol diagram for Remote Attestation 



1.7 RAserver 
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1.7 RAserver 



The server is separated into different methods representing each state of the Remote-Attestation 
protocol. The methods are called subsequently, 
seef 



RAclient for a detailed description of the Remote-Attestation protocol 



1 apps 
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2 jTPMtools 

de.fraunhofer.sit.tc.ethemba.jTPMtools 

This package contains modified source-code taken from jTPMtools. 
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2 jTPMtools 



2.1 AikUtil 

This class was copied and modified from iaik.tc.apps.jtt.aik.AikUtil. 

It is used within \PCAclienl\ to create EK- Certificates on-the-fly (which are passed to the 



PCAserver) . Additionally it is indirectly used within PCAserver and directly used within Pri- 



vacyCa to create AIK-Certificates (which are passed to the PCAclienfy . 



Modifications applied: 

• changed AIK- Certificate creation to use ethemba's global settings for certificate attributes 

• changed CA- Certificate creation to use ethemba's global settings for certificate attributes 

• changed EK- Certificate creation to use ethemba's global settings for certificate attributes 

• changed PE-Certificate creation to use ethemba's global settings for certificate attributes 



2.2 Client 
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2.2 Client 

This class was copied and slightly modified from iaik.tc.apps.jtt.aik.Client. 

It is used within PCAclient in state3 to run a TPM_CollateIdentityRequest command and in 
state4 and state6 to run a TPM_ActivateIdentity command. 

Modifications applied: 

• changed visibility of activateldentity from protected to public to have outer access 

• changed visibility of collateldentityReq from protected to public to have outer access 



changed visibility of overrideEkCertificate from protected to public to have outer access 
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2 jTPMtools 



2.3 PrivacyCa 



This class was copied and modified from iaik.tc.apps.jtt.aik. PrivacyCa. 



It is used within PCAserver to process the collateldentity request blob received from the PCA- 



client and wrapping a server-generated nonce inside a TPM blob that can only be accessed by 



the TPM itself. 

In another state of the AIK-Certification protocol (see PCAclient> the second collateldentity 
request blob received from the PCAclient is being processed and the resulting AIK-Certificate 
is again wrapped inside a TPM blob that can only be accessed by the TPM itself. 



See PCAclient for detailed information on the AIK-Certification protocol. 

Modifications applied: Two new methods were added to implement a handshake in the 
AIK-Certification protocol. The state3_sub method provides the wrapping of the server-generated 
nonce for the client instead of transmitting the certificate in the first step. In state3_sub the EK 
certificate is already validated. 

In this design, clients without a valid EK certificate will be rejected at an early stage in the 
protocol. A later verification of the EK certificate might be advantageous as it decreases the 
burden on the PCA in case the protocol stops during nonce verification. The AIK-Certificate is 
not issued in this stage. 

The method state5_sub provides a secure wrapping for the AIK-Certificate. First the AIK- 



Certificate is generated. A new one-time symmetric AES key is being generated and used to 
encrypt the certificate. The response consists of three parts: 

1. a symmetric session key and the hash of the AIK public key, both encrypted asymmetri- 
cally with the public EK of the client. Via this indirection, only the client is able to decrypt 
the session key. 



2. the symmetric l AESJ key previously used to encrypt the AIK-Certificate, encrypted with 
the session key 



3. the AIK-Certificate, encrypted with the AES| key 

The client can then decrypt the session key using the TPM_ActivateIdentity function of the 



TPM. This reveals the AES key, which can then in turn be used to decrypt the AIK-Certificate. 



3 modules 



DE.FRAUNHOFER. SIT. TC.ETHEMBA. MODULES 

This package contains modules providing storage /mapping methods for keys and certificates 
on the one hand and modules providing convenient TPM method handling (e.g. quote, bind, 
certify etc.) on the other hand. 
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3 modules 



3.1 client. CertDB 

3.1.1 Description 

CertDB saves X509-Certificates in a database mapping it to given UUIDs. 

3.1.2 PUBLIC getCert 
Description 

returns the corresponding certificate for the given UUID 

Settings 

CertDBfile 
Parameters 

TcTssUum uuid UUID of the certificate 

Output 

X509 Certificate corresponding certificate 

3.1.3 PUBLIC putCert 
Description 

puts a given certificate into the CertDB using the given UUID 

Settings 

CertDBfile 
Parameters 



TcTssUum uuid 


UUID of the certificate 


X509 Certificate cert 


certificate to be put into the CertDB 



3.1.4 PUBLIC removeCert 
Description 

removes a certificate from the CertDB 



Settings 

CertDBfile 
Parameters 

TcTssUum uuid UUID of the certificate 

3.1.5 PUBLIC exportCert 
Description 

exports a certificate to the disk 



3.1 client.CertDB 
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Settings 




CertDBfile 




Parameters 




TcTssUum uuid 


UUID of the certificate 


String outputFile 


location of the exported certificate 



3.1.6 PRIVATE loadDB 
Description 

loads the CertDB from the globally defined location 



Settings 

CertDBfile 
Parameters 

none 

Output 

Hashtable<String, byte[]> loaded database 



3.1.7 PRIVATE saveDB 



Description 




saves a given CertDB to the ; 


globally defined location 


Settings 




CertDBfile 




Parameters 




Hashtable<String, 


database to be saved 


BYTE[]> db 





26 



3 modules 



3.2 client. CertifyKey 
3.2.1 Description 

This client module can be used to create and certify a TPM key for binding or sealing. The 
created key is signed by a given AIK. 



CSK 



pub 



CSK 



RSA keypair 
creates 



TPM_CMK_CreateKey 
Step 1 



prv 



load key 
"into TPM~^ 



TPM_Loadkey 
Step 2 



PCA 



AIK 



pub 



cert(AIK,PCA cert ) 



1 



TPM_CertifyKey 
Step 3 



states that: 

this key is hold in a 

shielded TPM 

location 

(attestation of 

possession) 



AIK 



CSK 



pub 



cert(CSK,AIK) 



Figure 3.1: Creation of a CSK (Certified Signing Key) using a certified AIK 



3.2.2 CONSTRUCTOR CertifyKey 
Description 

takes the given input values and stores them internally for later passing it to the TPM via the 
run method 

Settings 
none 

Parameters 



boolean isBindingKey 


create a binding key (true ) or sealing key (false ) 


boolean isVolatile 


volatile or non-volatile key 


String srkPwd 


SRK-Password 


String keyPwd 


Key-Password 


String keyLabel 


Label to store created key under 


INT[] pcrSelection 


array to define, to which PCRs the key shall be bound to 


(optional) 


byte[] nonce 


nonce to be included in certification (anti-replay!) 


String aikPwd 


AIK-Password 


String aikLabel 


Label of AIK to be used for signing 



3.2.3 PUBLIC run 
Description 

Implements the necessary steps to create and certify a TPM key using the TPM. First the SRK 
(to store the key under) and AIK (to sign the key) are loaded and key attributes for the newly 



3.2 client.CertifyKey 27 



created key are being assigned. Then a composite object is created holding the selected PCRs 
given via the constructor. This data is passed to the TPM using the certifyKey method provided 



by jTSS (see References . After creating/ certifying the key, it is stored in the persistent storage 
and labeled with the given keyLabel. An Object [] is returned containing everything needed 
inf. 



server. CertifyKeyValidaton 



TcBlobData public key 
TcTssValidation keyCertification 
X509 Certificate AIK- Certificate 



Settings 

pwdEncoding, TPM_KeySize 
Parameters 
none 

Output 

Object[] containing [1] TcBlobData public key [2] TcTssValidation keyCertification, [3] 
X509 Certificate AIK- Certificate 
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3 modules 



3.3 client. CreateKey 
3.3.1 Description 

This client module can be used to create a TPM key for binding or sealing. 



3.3.2 CONSTRUCTOR CreateKey 
Description 

takes the given input values and stores them internally for later passing it to the TPM via the 
run method 



Settings 
none 

Parameters 



boolean isBindingKey 


create a binding key (true ) or sealing key (false ) 


boolean isVolatile 


volatile or non-volatile key 


boolean isMigratable 


migratable or non-migratable key 


String srkPwd 


SRK-Password 


String keyPwd 


Key-Password 


String keyLabel 




int[] pcrSelection 


array to define, to which PCRs the key shall be bound to 
(optional) 



3.3.3 PUBLIC run 
Description 

Implements the necessary steps to create a TPM key using the TPM. First the SRK (to store the 
key under) is loaded and key attributes for the newly created key are being assigned. Then a 
composite object is created holding the selected PCRs given via the constructor. This data is 
passed to the TPM using the createKey method provided by jTSS (see Reference^ . After creat- 
ing the key it is stored in the persistent storage and labeled with the given keyLabel. 



Settings 

pwdEncoding, TPM_KeySize 
Parameters 
none 



Output 

TcBlobData public part of created keypair 



3.4 client.DataBinding 
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3.4 client.DataBinding 
3.4.1 Description 

This client module can be used to bind (i.e. encrypt) data to the TPM. The bound data can only 
be unbound (i.e. decrypted) inside this TPM. 



3.4.2 CONSTRUCTOR DataBinding 
Description 

takes the given input values and stores them internally for later processing in the run method 



Settings 




none 




Parameters 




byte[] data 


data to be bound/encrypted 


String srkPwd 


SRK- Password 


String keyPwd 


Key-Password 


String keyLabel 


Label of the key to be used to bind the data 



3.4.3 PUBLIC run 



Description 

Implements the necessary steps to bind the given data using the public key belonging to the 
given keyLabel. First the key is loaded using the SRK. Then data is separated into chunks 



matching the keysize and passed to the bind method provided by jTSS (see References 



Settings 

pwdEncoding, TPM_KeySize 
Parameters 
none 



Output 

byte[] bound/ encrypted data 
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3 modules 



3.5 client. DataUnbinding 

3.5.1 Description 

This client module can be used to unbind (i.e. decrypt) once bound data. 

3.5.2 CONSTRUCTOR DataUnbinding 
Description 

takes the given input values and stores them internally for later processing in the run method 



Settings 

none 

Parameters 

byte[] data 

String srkPwd 
String keyPwd 
String keyLabel 



data to be bound/encrypted 

SRK-Password 

Key- Password 



Label of the key to be used to unbind the data 




3.5.3 PUBLIC run 
Description 

Implements the necessary steps to unbind the given data using the public key belonging to 
the given keyLabel. First the key is loaded using the SRK. Then data is separated into chunks 



matching the keysize and passed to the unbind method provided by jTSS (see References '. 



Settings 

pwdEncoding 
Parameters 

none 



Output 

byte[] unbound/decrypted data 



3.6 client.QuoteRetrieval 
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3.6 client.QuoteRetrieval 
3.6.1 Description 

This client module can be used to request and retrieve a quote from the TPM. The quote in- 
cludes the signed hash value of the desired PCRs and a signed nonce, as replay protection. The 
client must provide a valid certificate for the key used to sign the quote. Normally an AIK is 
used to sign the quote, so a previously acquired AIK certificate from PCAclienl^PCAserver can 
be used to verify the quote. 



3.6.2 CONSTRUCTOR QuoteRetrieval 



Description 

takes the given input values and stores them internally for later retrieval of the quote via the 
run method 



Settings 




none 




Parameters 




int[] pcrSelection 


array to define which PCRs shall be included in the quote 


byte [] nonce 


nonce to be included in quote (— ► replay protection) 


String srkPwd 


SRK password, needed to load the AIK 


String aikPwd 


AIK password, needed to load the AIK 



String aikLabel label that has been assigned to the AIK in a PCA process 



3.6.3 PUBLIC run 
Description 

Implements the necessary steps to retrieve the quote from the TPM. First the AIK is loaded 
using the SRK. Then a composite object is created holding the selected PCRs given via the con- 
structor. This data altogether with the nonce is passed to the TPM using the quote method 
provided by jTSS {see \Referencetf . After retrieving the quote, the AIK is unloaded from the TPM 
and the quote is returned to the calling method. 



Settings 

pwdEncoding 
Parameters 

none 



Output 

TcTssValidation the quote that was retrieved from the TPM 
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3.7 client. TpmKeyDB 

3.7.1 Description 

TpmKeyDB maps labels to UUIDs. This is used to allow convenient access to keys generated 
by the TPM. Those keys are separated by TPM generated UUIDs which are rather difficult to 
remember. TpmKeyDB allows to assign labels to those UUIDs and to access them in an easy 
way. 

3.7.2 PUBLIC getUUID 
Description 

returns the corresponding UUID for the given label 

Settings 

TpmKeyDBfile 
Parameters 

String label label to get the UUID for 

Output 

TcTssUuid corresponding UUID for the given label 



3.7.3 PUBLIC putUUID 



Description 




puts a label o UUID mapping 


; to the TpmKeyDB 


Settings 




TpmKeyDBfile 




Parameters 




String label 


label to be used 


TcTssUuid uuid 


UUID to be used 



3.7.4 PUBLIC removeUUID 
Description 

removes a label o UUID mapping from the TpmKeyDB 

Settings 

TpmKeyDBfile 
Parameters 

String label label whose mapping is to be removed 



3.7 client.TpmKeyDB 
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3.7.5 PRIVATE loadDB 
Description 

loads the TpmKeyDB from the globally defined location 

Settings 

TpmKeyDBfile 
Parameters 

none 

Output 

Hashtable<String, Strino loaded database 

3.7.6 PRIVATE saveDB 



Description 




saves a given TpmKeyDB to the 


globally defined location 


Settings 




TpmKeyDBfile 




Parameters 




Hashtable<String, 


database to be saved 


Strino db 
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3.8 server. CertifyKeyValidaton 



3.8.1 Description 



This server module can be used to validate a given output of a client. CertifyKey command. 
The included keyCertification is equipped with a signature and contains a nonce (-» replay 
protection) . First the signature is checked for validity, then the nonce is matched against the 
challenged one (see clien t. CertifyKey] . At last the digests of the included public key and the 
one contained in the output of client. CertifyKey are checked for identicalness. 



Note: CertifyKeyValidation only checks the result of a client.CertifyKey command for valid 



ity. One should verify the included AIK- Certificate for trustability after successful validation. 
The included public key may then be used in further steps. 



3.8.2 CONSTRUCTOR CertifyKeyValidaton 
Description 

takes the given input values and stores them internally for later validation of the certification 
via the run method 



Settings 

none 



Parameters 



Object [] certifyKeyResult result of the 

key, keyCert 


client. CertifyKey 
ification and AIK 


command, contains public 
-Certificate 


byte [] nonce nonce that was challenged and to validate the certifica- 
tion against 



3.8.3 PRIVATE createDigestlnfoDER 
Description 

code from jTPM-Tools. It is used to return the digestlnfo properly out of the certification. 



Settings 
none 

Parameters 

TcBlobData digest digest to be properly encoded 



Output 

TcBlobData digestlnfo used during verification of the certification signature 



3.8.4 PUBLIC run 



Description 

Implements the necessary steps to validate the given output of a previous client.CertifyKey 



3.8 server.CertifyKeyValidaton 
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command. 

First the signature of the keyCertification is validated against the AIK- Certificate included in 
client. CertifyKefo output. Then the nonce is checked against the given one. Finally the public 
key included in the output is checked against the one signed in the keyCertification. 

Note: Please be aware that this method only validates the output without verifying the 
trustability of the contained AIK-Certificate. This should be done after a successful valida- 
tion. 

Settings 

none 

Parameters 

none 

Output 

boolean true if certification is valid, else false 
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3.9 server. ExternalDataBinding 

3.9.1 Description 

This server module can be used to bind (i.e. encrypt) data to an external TPM using a pub- 
lic key of a TPM keypair resident inside the TPM. Bound data can only be unbound (i.e. de- 
crypted) inside the TPM it was bound to. 

3.9.2 CONSTRUCTOR ExternalDataBinding 
Description 

takes the given input values and stores them internally for later processing in the run method 

Settings 
none 

Parameters 



byte[] data 


data to be bound/encrypted 


TcBlobData key 


public key to be used to bind data 



3.9.3 PUBLIC run 
Description 

Implements the necessary steps to bind the given data using the given public key. Data is sep- 
arated into chunks matching the keysize and passed to the bind method provided by jTSS (see 
References'. 



Settings 

TPM_KeySize 
Parameters 
none 

Output 

byte[] bound/ encrypted data to be passed to the corresponding TPM 



3.10 server.KeyStorage 
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3.10 server.KeyStorage 



3.10.1 Description 



The server module server.KeyStorage provides easy access to save and load functions for server 
keys. It can be used to store public/private keypairs and provides an interface to retrieve the 
keys via tags. It is used by \PCAserver and RAserver to store their signing keys. If a keypair with 
the specified tag already exists, the older one will be overwritten. 



3.10.2 PRIVATE loadFromFile 
Description 

loads the mapping file from the predefined filesystem-location. 
Settings 

KeyStorageBaseDir, KeyStorageDB 
Parameters 
none 



3.10.3 PRIVATE saveToFile 
Description 

saves the mapping to the predefined filesystem-location 
Settings 

KeyStorageBaseDir, KeyStorageDB 
Parameters 
none 



3.10.4 PRIVATE getMapping 
Description 

returns the filename mapped to the given tag 

Settings 
none 

Parameters 

String tag tag to be searched for 

Output 

String [] filenames of key files mapped to the tag 
[0] public keyfile [1] private keyfile 
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3.10.5 PUBLIC getPublicKeyFile 
Description 

returns the filename of the public key 
Settings 

KeyStorageBaseDir 
Parameters 

String tag keypair tag 

Output 

String the filename of the public key to the given tag 

3.10.6 PUBLIC getPrivateKeyFile 
Description 

returns the filename of the private key 
Settings 

KeyStorageBaseDir 
Parameters 

String tag keypair tag 

Output 

String the filename of the private key to the given tag 

3.10.7 PUBLIC getPublicKey 
Description 

get the public key as PublicKey for the given tag 

Settings 
none 

Parameters 

String tag keypair tag 

Output 

PublicKey stored under the given tag 

3.10.8 PUBLIC getPrivateKey 
Description 

get the private key as PrivateKey for the given tag 



3.10 server.KeyStorage 
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Settings 
none 

Parameters 

String tag keypair tag 

Output 

PrivateKey stored under the given tag 



3.10.9 PUBLIC put 
Description 

put stores the given keypair in the files specified by the user. The user must provide a tag by 
which the keys can be accessed later. The keys will be stored in Settings.KeyStorageBaseDir, 
the mapping of tags to keys is stored in Settings.KeyStorageDB. 



Settings 




KeyStorageBaseDir 




Parameters 




String tag 


the user provided tag for the storage of the keypair 


String publicKeyFile 


the filename of the public key file 


PublicKey publicKey 


the public key to be stored 


String privateKeyFile 


the filename of the private key file 


PrivateKey privateKey 


the private key to be stored 



Output 

String!] of replaced entries, if tag already existed m\server. Key 'Storage 



3.10.10 PUBLIC putPublicKey 
Description 

stores the given public key in the file specified by the user. The user must provide a tag by 
which the key can be accessed later. The key will be stored in Settings.KeyStorageBaseDir, the 
mapping of tags to keys is stored in Settings.KeyStorageDB. 

Settings 

KeyStorageBaseDir 
Parameters 



String tag 


the user provided tag for the storage of the keypair 


String publicKeyFile 


the filename of the public key file 


PublicKey publicKey 


the public key to be stored 



Output 

String!] of replaced entries, if tag already existed in 



server. Key Storage 
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3.10.11 PUBLIC putPrivateKey 
Description 

stores the given private key in the file specified by the user. The user must provide a tag by 
which the key can be accessed later. The key will be stored in Settings.KeyStorageBaseDir, the 
mapping of tags to keys is stored in Settings.KeyStorageDB. 

Settings 

KeyStorageBaseDir 
Parameters 



String tag 


the user provided tag for the storage of the keypair 


String privateKeyFile 


the filename of the public key file 


PrivateKey privateKey 


the private key to be stored 



Output 

String [] of replaced entries, if tag already existed in server. Key Storage 



3.11 server.QuoteValidation 
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3.11 server.QuoteValidation 
3.11.1 Description 



The server module server.QuoteValidation can be used to validate a given quote from a TPM. 
The quote includes the signed hash value of the desired PCRs and a signed nonce (— ► replay 
protection). The client must provide a valid certificate for the key used to sign the quote. 



Normally an AIK is used to sign the quote, so a previously acquired AIK certificate from PCA- 
clien tflPCAserver can be used to verify the quote. 



The validation of the quote consists of two major parts: 

1. Verification of the signature: the public key used for signing is used to verify the given 
signature on the nonce and the PCR data. 

2. Verification of quote contents: it is verified that the original nonce, supplied by the 
server, is included in the client's quote. Furthermore, the quote contains the hash value 
of all quoted PCRs. A pre-calculated PCR value can be supplied to server. QuoteValidation\ 



so that validation will only succeed if the pre-calculated value matches the quoted PCR 
value. 



3.11.2 CONSTRUCTOR QuoteValidation 



Description 

takes the given input values and stores them internally for later validation of the quote via the 
run method 



Settings 

none 



int[] pcrSelection 


array to define which PCRs have been included in the 
given quote 


TcTssValidation quote 


quote as received from the attesting client 


X509 Certificate aikCert 


certificate belonging to the key used for signing. It is pro- 
vided by the client to retrieve the public key and verify 
the quote's signature. 


BYTE[][] VPCRS 


pre-calculated vPCR values are provided as byte [] . Mul- 




tiple vPCRs can be provided. 


byte[] nonce 


the anti-replay nonce the server previously provided for 
the client to be included in the quote 



3.11.3 PRIVATE selectPCR 



Description 

the method is used to return a TcBlobData structure with a byte[] representation of a se- 
lected PCR. The bit at the given index i is set to 1, all other bits are 0. 
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Settings 
none 

Parameters 

long index index of PCR to select 

Output 

TcBlobData containing the byte[] representation of the selected PCR 

3.11.4 PRIVATE createDigestlnfoDER 
Description 

code from jTPM-Tools. It is used to return the digestlnfo properly out of the quote. 

Settings 
none 

Parameters 

TcBlobData digest digest to be properly encoded 

Output 

TcBlobData digestlnfo used during verification of the quote signature 

3.11.5 PUBLIC run 
Description 

Implements the necessary steps to validate the given quote. First the public key is extracted 
from the supplied certificate. It is used to verify the quote's signature. A composite object 
with the given pre-calculated PCR values is created and its hash value is calculated. The hash 
is checked against the hash value provided by the quote. Finally the quote's nonce is checked. 
Only if all steps of the validation succeed, the quote will validate. Protection is provided against 
different attacks. If quote contents are changed after signing, the validation of the signature 
will fail. If a malicious client provides a modified measurement list, pretending to run only 
trusted software, the calculated vPCR will not match the quoted and signed PCR value. Anti- 
replay attack protection is given by the usage of the rolling nonce. 

Settings 

none 

Parameters 

none 

Output 

boolean true if quote is valid, else false 



4 net 

DE.FRAUNHOFER.SIT.TC.ETHEMBA.NET 

This package contains networking classes for sending and receiving data via TCP/IP. 
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4.1 NetEntity 

4.1.1 Description 

NetEntity provides an implementation of a networked client-server infrastructure. NetEntity 
can be initialized as server or as client. Once initialized, it can be used to transfer controls 
I NetCommand\ or Objects. 

4.1.2 CONSTRUCTOR NetEntity 
Description 

Sets up a NetEntity as either server or client. If invoking with serverHostname and serverPort, 
a client version is instantiated. If only serverPort is given, a server is instantiated 



Settings 




none 




Parameters 




String serverHostname 


hostname of server the client will connect to (client only) 


int serverPort 


port the client will connect to / the server will listen on 



4.1.3 PUBLIC init 
Description 

Initializes the connection. A socket is created and bound to the specified port. If instance is a 
server, the socket will start to listen and accept connections. 



Settings 

none 

Parameters 

none 

4.1.4 PUBLIC close 
Description 

closes the socket. Returns true , if socket closed successfully, else false . 

Settings 

none 

Parameters 

none 

4.1.5 PUBLIC sendACK 
Description 

sends a \NetCommandl ACK 



4.1 NetEntity 
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Settings 

none 

Parameters 

none 

Output 

true , if sent successfully, else false 

4.1.6 PUBLIC sendNACK 
Description 

sends a l Net Command NACK 

Settings 

none 

Parameters 

none 

Output 

true , if sent successfully, else false 

4.1.7 PUBLIC sendCommand 
Description 



sends the given NetCommand 



Settings 
none 

Parameters 



NetCommand netCom- the NetCommand to be sent 



mand 
Output 

true , if sent successfully, else false 

4.1.8 PUBLIC sendObject 
Description 

sends the given object over the connection. 

Settings 

none 
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Parameters 

Object o object to send 

Output 

true if sent successfully, else false 



4.1.9 PUBLIC receiveACK 

Description 

try to receive a 



NetCommand ACK 



Settings 

none 

Parameters 

none 



Output 

true if ACK received, else false 



4.1.10 PUBLIC receiveCommand 

Description 

receive a \NetCommand\ 



Settings 

none 

Parameters 

none 



Output 

returns the received NetCommand if received object is an integer. Else NetCommand\ UNKNOWN 
is returned 



4.1.11 PUBLIC receiveObject 
Description 

waits to receive an Object of the given class. 



Settings 
none 

Parameters 

Class c class of the object to be received 



4.1 NetEntity 
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Output 

If received object is of specified type, the object is returned, else null. 

4.1.12 PUBLIC getRemotelP 
Description 

returns the IP address of the client, when issued on the server 

Settings 

none 

Parameters 

none 

Output 

String IP address of client 

4.1.13 PUBLIC getRemoteHostname 
Description 

returns the hostname of the client, when issued on the server 

Settings 

none 

Parameters 

none 

Output 

String hostname of client 
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4.2 NetCommand 
4.2.1 Description 

NetCommand provides a mapping between symbolic names and command codes (int) for 
convenient use of NetEntity objects. 

UNKNOWN 
ACK 
NACK 
INIT 
CLOSE 

KNOWNHASHES 
STRING 
RA_REQUEST 
RA_RESPONSE 
PCA_REQUEST 
PCA_RESPONSE 



5 types 

DE.FRAUNHOFER. SIT. TC.ETHEMBA. TYPES 

This package contains data types for convenient access to IMA measurements and hash lists. 
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5.1 MeasurementList 

5.1.1 Description 

MeasurementList is a data type for convenient conversion and access to IMA measurement 
data. 

5.1.2 CONSTRUCTOR MeasurementList 
Description 

initializes the MeasurementList with a String [] [] [] 

Settings 
none 

Parameters 

String[] [] [] measure- [1] PCR number 
mentList [2] hash 

[3] application 

5.1.3 PUBLIC getMeasurementList 
Description 

returns the MeasurementList as string array representation 

Settings 

none 

Parameters 

none 

Output 

String [] [] [] string array representation of the MeasurementList 

5.1.4 PUBLIC getMeasurementListForPCR 
Description 

returns the MeasurementList for a given PCR number as string array representation 

Settings 
none 

Parameters 

int per to be filtered PCR number 

Output 

String [] [] string array representation of the MeasurementList for the given PCR number 



5.1 MeasurementList 
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5.1.5 PUBLIC loadFromFile 
Description 

loads MeasurementList from a file in IMA-Measurement-Format 

Settings 
none 

Parameters 

String filename file to load MeasurementList from 

Output 

MeasurementList loaded MeasurementList 
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5.2 KnownHashesList 

5.2.1 Description 

KnownHashesList is a data type providing basic database abilities for storing known hash o 
application mappings. 

5.2.2 CONSTRUCTOR KnownHashesList 
Description 

initializes the KnownHashesList 

Settings 
none 

Parameters 

none 

5.2.3 PUBLIC put 
Description 

maps the given hash to the given tag 

Settings 
none 

Parameters 



String shalhash 


hash of a application 


String tag 


path and name of the application that was hashed 



Output 

String tag/ application that was associated to the given tag before, else null 

5.2.4 PUBLIC get 
Description 

returns the tag to which the specified hash is mapped to 

Settings 
none 

Parameters 

String shalhash hash to be searched for 

Output 

String tag/application that hash is associated to, else null 



5.2 KnownHashesList 
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5.2.5 PUBLIC containsTag 
Description 

tests if the given tag/ application is mapped to one ore more hashes 

Settings 
none 

Parameters 

String tag tag/ application to be searched for 

Output 

true if given tag/ application is associated with one or hashes, else false 

5.2.6 PUBLIC containsShalHash 
Description 

tests if the given hash is mapped to a tag/ application 

Settings 
none 

Parameters 

String shalhash hash to be searched for 

Output 

true if given hash is associated with a tag/ application, else false 

5.2.7 PUBLIC contains 
Description 

tests if a given hash is mapped to a given tag/ application 

Settings 

none 



Parameters 



String shalhash 


hash to be searched for 


String tag 


tag/ application to be associated with 



Output 

true if given hash is associated with the given tag/ application, else false 

5.2.8 PUBLIC saveToFile 
Description 

saves KnownHashesList to a given file 
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Settings 
none 

Parameters 

String filename file to save KnownHashesList in 

5.2.9 PUBLIC loadFromFile 
Description 

loads a KnownHashesList from the disk 

Settings 
none 

Parameters 

String filename file to load KnownHashesList from 

Output 

KnownHashesList loaded KnownHashesList or null if KnownHashesList could not be loaded 



6 utils 



DE.FRAUNHOFER.SIT.TC.ETHEMBA.UTILS 

This package contains classes and methods for data conversion and standardized algorithms, 
that may be accessed in a convenient way. 



55 



56 



6 utils 



6.1 AES 

6.1.1 Description 

AES provides access to various AES calculations (encryption/ decryption). Each method may 
also be accessed in a static way. Be aware to pass enough data to the static methods (i.e. AES- 
KeyandlV). 

Additionally random and pseudo-random AES-Keys and IVs may be generated using this 
class. 

6.1.2 CONSTRUCTOR AES 
Description 

constructs an AES object with the given key and initialization vector (IV) 

Settings 
none 

Parameters 



SecretKey k 


AES key 


BYTE [] IV 


initialization vector (IV) 



6.1.3 PUBLIC encryptObject 

Description 

encrypts a given Object 

Settings 
none 

Parameters 

Object m object to be encrypted 

Output 

byte[] encrypted data 

6.1.4 PUBLIC encrypt 

Description 

encrypts a given byte [] 

Settings 
none 

Parameters 

byte [] m data to be encrypted 



6.1 AES 
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Output 

byte[] encrypted data 

6.1.5 PUBLIC decryptObject 
Description 

decrypts a given byte[] back into an Object 

Settings 
none 

Parameters 

byte[] c data to be decrypted 

Output 

Object decrypted object 

6.1.6 PUBLIC decrypt 

Description 

decrypts a given byte[] 

Settings 
none 

Parameters 

byte[] c data to be decrypted 

Output 

byte[] decrypted data 

6.1.7 PRIVATE crypt 
Description 

en- or decrypts given byte [] with given AES-Key and IV 
Settings 

aesCipherMode, aesKeySize 
Parameters 



int optMode 


operation mode: Cipher.DECRYPT_MODE or Ci- 




pher. ENCRYPT_MODE 


SecretKey k 


AES-Key to be used 


BYTE [] IV 


IV to be used 


byte[] input 


data to be en- or decrypted 
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Output 

byte[] en- or decrypted data 

6.1.8 PUBLIC generateKey 
Description 

generates a random AES-Key 

Settings 

none 

Parameters 

none 

Output 

SecretKey generated key 

6.1.9 PUBLIC generateKey 
Description 

generates a pseudo-random AES-Key by using an initial seed 

Settings 
none 

Parameters 

byte [] seed initial seed for PRNG 

Output 

SecretKey generated key 

6.1.10 PUBLIC generatelV 
Description 

generates a pseudo-random IV by using an initial seed 

Settings 
none 

Parameters 

byte[] seed initial seed for PRNG 

Output 

byte[] generated IV 



6.2 Helpers 
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6.2 Helpers 

6.2.1 Description 

Helpers provides some useful methods for data conversion and serialization. 

6.2.2 PUBLIC byteToHexString 
Description 

converts a given byte [] into a Hex- String 

Settings 
none 

Parameters 

byte[] data data to be converted 

Output 

String Hex-String representation of given data 

6.2.3 PUBLIC hexStringToByteArray 
Description 

converts a given Hex- String into a byte[] 

Settings 
none 

Parameters 

String hexstring string to be converted 

Output 

byte[] converted data 

6.2.4 PUBLIC leadingZeroes 
Description 

adds leading zeroes to a given number 

Settings 
none 

Parameters 



int num 


number to be padded with zeroes 


int length 


length of result 



Output 

String string representation of given number with padded zeroes to match the given length 
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6.2.5 PUBLIC saveObjectToFile 
Description 

saves a given object (needs to be serializable) to the disk 

Settings 
none 

Parameters 



Object o 


object to be saved 


String filename 


location of saved object 



6.2.6 PUBLIC saveBytesToFile 

Description 

saves bytes to a file 

Settings 

none 



Parameters 



BYTE[] b 


bytes to be saved 


String filename 


file to be saved to 


6.2.7 PUBLIC loadObjectFromFile 


Description 




loads an object from a given file 




Settings 




none 




Parameters 




String filename 


file to load object from 


Output 




Object loaded from given file 




6.2.8 PUBLIC loadBytesFromFile 



Description 

loads a file byte-wise 



Settings 
none 

Parameters 

String filename file to be loaded from 



6.2 Helpers 
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Output 

byte[] loaded bytes 

6.2.9 PUBLIC Object2Bytes 
Description 

converts an object to bytes 

Settings 
none 

Parameters 

Object o object to be converted 

Output 

byte[] converted bytes 

6.2.10 PUBLIC Bytes20bject 
Description 

converts a bytes back to an object 

Settings 
none 

Parameters 

byte[] b bytes to be converted 

Output 

Object converted object 
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6.3 SHA1 

6.3.1 Description 

SHAl provides access to various SHA1 calculations. 

6.3.2 PUBLIC main 
Description 

generates SHAl -Hash of given string/hex-string 

Settings 
none 

Parameters 



String[] args 


[0] String to be hashed 




[1] if '-h the given String is assumed to be a hex repre- 




sentation 



Output 

SHAl -Hash of given data 



6.3.3 PUBLIC hashByteToByte 
Description 

calculates SHAl-Hash of given byte[] 

Settings 
none 

Parameters 

byte[] input data to be hashed 

Output 

byte [ ] SHAl -Hash of given data 

6.3.4 PUBLIC hashHex 
Description 

calculate SHAl-Hash for given Hex-String 

Settings 
none 

Parameters 

String input data to be hashed (Hex-String) 



6.3 SHA1 
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Output 

String SHAl-Hash of given data 

6.3.5 PUBLIC hash 
Description 

calculate SHAl-Hash for given String 

Settings 
none 

Parameters 

String input data to be hashed 

Output 

String SHAl-Hash of given data 

6.3.6 PUBLIC randomHash 
Description 

returns SHAl-Hash of a random generated number 

Settings 

none 

Parameters 

none 

Output 

byte[] of SHAl-Hash 



6 utils 
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7 Demonstrators 



For demonstration purposes we provide two simple yet useful demonstrators. These demon- 
strators will prove that the Remote Attestation Protocol developed and implemented in ethemba 
serves as reliable attestation method. 

To prove reliability the following demonstrators inject bad code into an application that was 
added to the RAserver\ s KnownHashesList This KnownHashesList acts as a white-list repre- 
senting SHA1 hashes for well-known and valid applications. If an application was run on the 
attesting system that either is not included in the KnownHashesList or whose SHA1 hash does 
not match the one inside the KnownHashesList, Remote Attestation fails. 

To prove this we provide a demonstrator that will compile a C-program out of two sources. 
The demonstrators can be found in the subfolder demo and contain the following files: 



demoevil.sh 



demogood.sh 



helloworldevil.c 



helloworldgood.c 



7.1 demogood.sh 

This demonstrator will compile the code contained in helloworldgood.c to the binary hel- 
loworld. 

#include <stdio.h> 

int main() 

{ 

printf ( "sawubona! \n" ) ; 
printf ( "means^ 'hello ' i _,in i _ i zulu\n" ) ; 
return 0; 



Listing 7.1: helloworldgood.c 




We assume this code to be "good" and therefore included its SHA hash into the RAserver's 
KnownHashesList. Executing this program will not break a successful Remote Attestion. 
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7 Demonstrators 



7.2 demoevil.sh 

This demonstrator will compile the code contained in helloworldevil.c to the binary helloworld. 




Listing 7.2: helloworldevil.c 



This can be seen as an attack pretending execution of a well-known program. As its SHA1 
hash now differs from the one included in the RAserver's KnownHashesList, Remote Attestion 
now has to fail. 
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References 



ethemba uses jTSS as underlying implementation of the TCG Software Stack for Java. 

jTSS implements all the TSS layers directly in Java by staying very close to the TPM specifi- 
cations stated by the TCG. It is developed and maintained at the Institute for Applied Informa- 
tion Processing and Communication (Institut fur angewandte Informationsverarbeitung und 
Kommunikation, IAIK) at Graz University of Technology (TU Graz) . 

IAIK additionally provides a set of command line tools for basic operations on TPMs. These 
tools include several modules for attesting a platform (e.g. generate AIKs, certificates and han- 
dle TPM quotes). 



Some code of jTPM tools was re-used in ethemba to allow for convenient and reliable access. 



These modified modules can be found in a separate package underneath ethemba jTPM- 



For further information on jTSS and the OpenTC Project visit the following websites: 

Trusted Computing for the Java Platform 
|http : //t rusted java . source forge . net| 

OpenTC Project 
|http : / /www, opentc . net| 

Institute for Applied Information Processing and Communications 
|http : //www . iaik . tugraz . at| 
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..just in case you didn't know.. 



